feat(workflows): expose installed workflow listing through MCP by n1shanthb · Pull Request #5115 · github/spec-kit

n1shanthb · 2026-10-25T13:38:00Z

Description

Adds specify_workflow_list as a focused follow-up to #5054 for #4913.

Extracts a typed, transport-neutral operation shared by CLI and MCP.
Preserves CLI ordering, formatting, warnings, defaults, and error handling.
Adds strict contracts, bounded responses, safe project-path handling, and structured errors.
Marks only workflow.list as MCP-available while preserving the existing six tools.
Adds focused regression tests and MCP documentation.

The shared operation performs no filesystem writes, network requests, or subprocess execution.

Testing

Tested locally with uv run specify --help
Ran the complete suite in WSL after installing test dependencies with uv sync --extra test
Tested manually with a sample project (not performed)

Full WSL result: 12,782 passed, 440 skipped, 38 failed. All 38 failures reproduced on unchanged upstream 27d14e2; they concern PowerShell interoperability, paths containing spaces, and test download executables. No patch regression was identified in that comparison.

Additional validation:

Focused Windows tests: 69 passed, five skipped, one deselected, including passing junction safety tests.
Ruff, scoped mypy, and git diff --check passed.
Repeated stdio testing reproduced intermittent timeouts on unchanged upstream.
Compatibility probes verified legacy registry decoding behavior and correct invalid_operation_result mapping.

AI Disclosure

I did not use AI assistance for this contribution
I did use AI assistance

AI disclosure: OpenAI Codex (GPT-6.1 sol, autonomous execution under user direction) assisted with source investigation, implementation, test and documentation generation, automated review, validation, and drafting this PR description. Reasoning effort was not independently recorded. No line-by-line human review is claimed.

Assisted-by: OpenAI Codex (model: GPT-6, autonomous) Signed-off-by: Nishanth <bnishanthtpm06@gmail.com>

Copilot

🟡 Changes recommended

The new operation misclassifies missing or non-directory project paths as unsafe workflow storage.

1 open issue

Check project directory before accessing project files · New

What changed in this PR

Adds installed-workflow listing to MCP as an incremental follow-up to #5054 and #4913, sharing application behavior with the existing CLI.

Changes:

Extracts a typed, read-only workflow-list operation shared by CLI and MCP.
Adds specify_workflow_list with strict schemas, response limits, project-path checks, and structured errors.
Updates inventory registration, regression coverage, and MCP documentation while retaining the six existing tools.

File	Description
`tests/specify_cli/workflows/test_operation_list.py`	Tests shared behavior, storage safety, and read-only boundaries.
`tests/specify_cli/workflows/test_mcp.py`	Binds inventory parity to the implemented list contract.
`tests/specify_cli/workflows/test_mcp_list.py`	Tests schemas, dispatch, limits, errors, and protocol behavior.
`tests/specify_cli/workflows/test_command_list.py`	Checks CLI output compatibility and complete listings.
`tests/specify_cli/mcp_server/test_stdio.py`	Exercises workflow listing through real stdio.
`tests/specify_cli/mcp_server/test_server.py`	Updates expected tool discovery.
`src/specify_cli/workflows/mcp_list.py`	Implements the bounded, typed MCP adapter.
`src/specify_cli/workflows/command_list.py`	Delegates CLI listing to the shared operation.
`src/specify_cli/workflows/catalog/_domain.py`	Supports policy-aware registry reads.
`src/specify_cli/workflows/_storage.py`	Centralizes workflow storage validation.
`src/specify_cli/workflows/_operation_list.py`	Defines the shared listing contract and operation.
`src/specify_cli/workflows/_mcp.py`	Marks and registers only workflow listing as available.
`src/specify_cli/workflows/_commands.py`	Reuses centralized storage validation.
`src/specify_cli/mcp_server/server.py`	Registers the workflow-owned MCP tool.
`docs/reference/mcp.md`	Documents listing inputs, outputs, limits, and safety boundaries.

_{Review effort: Max}

mnriem · 2026-10-26T15:27:45Z

Please address Copilot feedback

Assisted-by: OpenAI Codex (model: GPT-6, autonomous) Signed-off-by: Nishanth <bnishanthtpm06@gmail.com>

n1shanthb · 2026-10-27T08:36:20Z

Thanks @mnriem. Addressed the Copilot feedback in 9c72389.

The fix validates the project directory before accessing workflow storage, so missing directories and regular files now return not_a_spec_kit_project rather than unsafe_workflow_storage. I also added operation-level and MCP regression coverage while preserving permission and storage error handling.

Validation: 72 passed on Windows and 1,843 passed in relevant Linux suites. Ruff, formatting, scoped mypy, and git diff --check also passed.

AI assistance: OpenAI Codex (GPT-6, autonomous under my direction) assisted with the fix, regression tests, validation.

Copilot

🟡 Changes recommended

An embedded NUL in an absolute project_directory triggers an uncaught ValueError, causing the adapter to return internal_error instead of not_a_spec_kit_project.

1 open issue

Handle NUL paths without uncaught ValueError · New

1 resolved since last review

Check project directory before accessing project files

_{Review effort: Max}

Assisted-by: OpenAI Codex (model: GPT-6, autonomous) Signed-off-by: Nishanth <bnishanthtpm06@gmail.com>

n1shanthb · 2026-10-28T06:35:09Z

Addressed in e173581. Embedded-NUL project paths now return not_a_spec_kit_project, while permission and filesystem policy error handling remain unchanged.

The new MCP regression test failed before the fix and passes afterward. Focused tests: 73 passed, 5 skipped on Windows; 76 passed, 2 skipped in WSL. Ruff, formatting, scoped mypy, and git diff --check passed. The full suite was not rerun.

AI assistance: OpenAI Codex (GPT-6, autonomous under my direction) assisted with the fix, regression test and validation.

Copilot

🟡 Changes recommended

The MCP documentation incorrectly lists invalid_limit as a structured error even though input validation rejects out-of-range limits with a text-only tool error.

1 open issue

Out-of-range limits are rejected by input validation before the operation runs, so clients receive… · New

1 resolved since last review

Handle NUL paths without uncaught ValueError

_{Review effort: Max}

mnriem · 2026-10-28T14:30:50Z

Please address Copilot feedback. If not applicable, please explain why

Assisted-by: OpenAI Codex (model: GPT-6, autonomous) Signed-off-by: Nishanth <bnishanthtpm06@gmail.com>

Copilot

🟡 Changes recommended

The extracted storage check omits path from the existing non-directory diagnostic, changing CLI error text that was meant to remain unchanged.

1 open issue

The extracted check drops path from the existing non-directory diagnostic, so workflow commands… · New

1 resolved since last review

Out-of-range limits are rejected by input validation before the operation runs, so clients receive…

_{Review effort: Max}

Assisted-by: OpenAI Codex (model: GPT-6, autonomous) Signed-off-by: Nishanth <bnishanthtpm06@gmail.com>

Copilot

🔵 Needs a closer look

Human assessment is needed to weigh the low-severity concern that command registration eagerly loads the catalog domain for unrelated CLI commands.

No open issues 🎉

1 resolved since last review

The extracted check drops path from the existing non-directory diagnostic, so workflow commands…

_{Review effort: Max}

mnriem · 2026-10-28T16:28:33Z

Thank you!

feat(workflows): expose installed workflow listing through MCP

b6c5311

Assisted-by: OpenAI Codex (model: GPT-6, autonomous) Signed-off-by: Nishanth <bnishanthtpm06@gmail.com>

n1shanthb requested a review from mnriem as a code owner October 25, 2026 13:38

mnriem added the triage-nice-to-have Verdict: evidence-backed fix or greenlit feature — land after review label Oct 25, 2026

mnriem requested a max review from Copilot October 26, 2026 14:01

Copilot started reviewing on behalf of mnriem October 26, 2026 14:01

View session

Copilot AI reviewed Oct 26, 2026

View reviewed changes

Comment thread src/specify_cli/workflows/_operation_list.py Outdated

fix(workflows): validate project directory before storage access

9c72389

Assisted-by: OpenAI Codex (model: GPT-6, autonomous) Signed-off-by: Nishanth <bnishanthtpm06@gmail.com>

mnriem requested a max review from Copilot October 27, 2026 19:23

Copilot started reviewing on behalf of mnriem October 27, 2026 19:23

View session

Copilot AI reviewed Oct 27, 2026

View reviewed changes

Comment thread src/specify_cli/workflows/_operation_list.py Outdated

fix(workflows): reject embedded NUL project paths

e173581

Assisted-by: OpenAI Codex (model: GPT-6, autonomous) Signed-off-by: Nishanth <bnishanthtpm06@gmail.com>

mnriem requested a max review from Copilot October 28, 2026 13:44

Copilot started reviewing on behalf of mnriem October 28, 2026 13:44

View session

Copilot AI reviewed Oct 28, 2026

View reviewed changes

Comment thread docs/reference/mcp.md Outdated

mnriem added the author-awaiting Waiting on author response label Oct 28, 2026

docs(workflows): clarify MCP limit validation errors

6c7db40

Assisted-by: OpenAI Codex (model: GPT-6, autonomous) Signed-off-by: Nishanth <bnishanthtpm06@gmail.com>

mnriem removed the author-awaiting Waiting on author response label Oct 28, 2026

mnriem requested a max review from Copilot October 28, 2026 14:37

Copilot started reviewing on behalf of mnriem October 28, 2026 14:38

View session

Copilot AI reviewed Oct 28, 2026

View reviewed changes

Comment thread src/specify_cli/workflows/_storage.py Outdated

fix(workflows): preserve storage diagnostic text

eb64425

Assisted-by: OpenAI Codex (model: GPT-6, autonomous) Signed-off-by: Nishanth <bnishanthtpm06@gmail.com>

mnriem requested a max review from Copilot October 28, 2026 15:49

Copilot started reviewing on behalf of mnriem October 28, 2026 15:50

View session

Copilot AI reviewed Oct 28, 2026

View reviewed changes

mnriem merged commit 749a177 into github:main Oct 28, 2026
16 checks passed

Navigation Menu

Repository navigation

feat(workflows): expose installed workflow listing through MCP - #5115

feat(workflows): expose installed workflow listing through MCP#5115
mnriem merged 5 commits into
github:mainfrom
n1shanthb:feat/4913-workflow-list-mcp

n1shanthb commented Oct 25, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

mnriem commented Oct 26, 2026

Uh oh!

n1shanthb commented Oct 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

n1shanthb commented Oct 28, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

mnriem commented Oct 28, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

mnriem commented Oct 28, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

n1shanthb commented Oct 25, 2026

Description

Testing

AI Disclosure

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

mnriem commented Oct 26, 2026

Uh oh!

n1shanthb commented Oct 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

n1shanthb commented Oct 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

mnriem commented Oct 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Uh oh!

mnriem commented Oct 28, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants